Root cause (finally)

Two hard Render constraints, confirmed empirically + via Render docs:

1. A static site is capped at 200 routes. Our set was 215 → the Blueprint sync failed on "Update web service routes". (The earlier "bad rule" /resources/infrastructure/api was a red herring — it was simply route #201.)
2. Blueprints MERGE routes and never delete them. So render.yaml-defined routes accumulate and drift, and can't be cleanly curated.

Together these make the Blueprint a poor place to own a redirect set. So routes move into code, applied via the Render API.

Approach

• redirects.config.js stays the single source of truth (202 entries).
• scripts/sync-render-routes.mjs consolidates to 116 routes and applies them via PUT /v1/services/{id}/routes (atomic replace — deletes anything not in the list, priority = list order):
  • 11 verified prefix-swap wildcard collapses (e.g. /react/* → /advanced/react-hooks/*, /resources/* → /api-and-toolings/*) replace 97 individual redirects. Each collapse is checked at build time — if any member isn't a clean tail-preserving swap, it's skipped and stays individual.
  • 94 individual redirects + the SPA-fallback rewrites, ordered redirects before rewrites (Render is first-match-by-priority), deduped by source.
  • Build fails if the result exceeds 200 routes or has duplicate sources.
• .github/workflows/render-routes.yml validates on every PR (no secrets) and applies on push to main (needs RENDER_API_KEY + RENDER_SERVICE_ID secrets).
• render.yaml keeps only service config (build/domains/env) — no routes block, so the Blueprint manages infra and never fights the API-managed routes.
• Removes the obsolete render.yaml splice script and redirects-in-sync workflow.

Behavior note

The 11 collapses are catch-alls (e.g. any /react/... now redirects to /advanced/react-hooks/...), so unlisted sub-paths redirect too instead of 404ing — generally an improvement. All 201 originally-mapped URLs resolve identically.

Verified end-to-end

On a throwaway Render static site, the 116-route set PUT succeeded and legacy URLs return correct 301s:

/sdk/getting-started/quickstart        -> 301 /get-started/quickstart
/resources/infrastructure/api          -> 301 /api-and-toolings/infrastructure/api   (via /resources/* wildcard)
/react/use-kernelclient                -> 301 /advanced/react-hooks/use-kernelclient  (wildcard tail)
/smart-wallet/permissions/policies/gas -> 301 /smart-accounts/permissions/policies/gas

Before this works in prod

1. Add repo secrets RENDER_API_KEY and RENDER_SERVICE_ID (srv-cm3hg30cmk4c73cd5nd0).
2. First apply replaces the prod service's current routes with the 116-route set.